Login

Authenticate a user and receive a JWT access token

POST /auth/login

Login

cURL

curl --request POST \
  --url https://api.example.com/auth/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "password": "<string>"
}
'

200 - Success

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3YzhmMWI0Zi0yZTNhLTRhOWItOGY2ZC0xYzJkM2U0ZjVhNmIiLCJlbWFpbCI6Imp1YW4ucGVyZXpAeXVjYXRhbi5nb2IubXgiLCJyb2xlcyI6ImFkbWluIiwiaWF0IjoxNzA5NTY3ODkwLCJleHAiOjE3MDk2NTQyOTB9.xK8pL9mN2qR3sT5vW7xY9zA1bC3dE4fG5hI6jK7lM8n",
  "user": {
    "id": "7c8f1b4f-2e3a-4a9b-8f6d-1c2d3e4f5a6b",
    "email": "[e-mail]",
    "roles": "admin",
    "mustChangePassword": false
  }
}

Description

Authenticates a user with their email and password. On successful authentication, returns a JWT access token and user information. The token should be included in the Authorization header for subsequent API requests.

Request Body

email · string · required

User’s email address

password · string · required

User’s password

Response

access_token · string

JWT access token for authentication. Include this token in the Authorization header as Bearer {token} for subsequent requests.

user · object

User information object

Show User object properties

id · string

Unique user identifier (UUID)

email · string

User’s email address

roles · string

User role. Possible values: admin or user

mustChangePassword · boolean

Indicates whether the user must change their password on next login

Response Examples

200 - Success

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3YzhmMWI0Zi0yZTNhLTRhOWItOGY2ZC0xYzJkM2U0ZjVhNmIiLCJlbWFpbCI6Imp1YW4ucGVyZXpAeXVjYXRhbi5nb2IubXgiLCJyb2xlcyI6ImFkbWluIiwiaWF0IjoxNzA5NTY3ODkwLCJleHAiOjE3MDk2NTQyOTB9.xK8pL9mN2qR3sT5vW7xY9zA1bC3dE4fG5hI6jK7lM8n",
  "user": {
    "id": "7c8f1b4f-2e3a-4a9b-8f6d-1c2d3e4f5a6b",
    "email": "[e-mail]",
    "roles": "admin",
    "mustChangePassword": false
  }
}

Code Examples

cURL

curl -X POST https://api.yucatan.gob.mx/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "SecurePassword123!"
  }'

Authentication Flow

1. Send a POST request to /auth/login with valid email and password
2. Receive the JWT access_token in the response
3. Store the token securely (e.g., in localStorage, sessionStorage, or secure cookie)
4. Include the token in the Authorization header for all subsequent API requests:
   Authorization: Bearer {access_token}
   
5. The token contains the user’s ID, email, and roles encoded in the JWT payload

Error Handling

Status Code	Description
200	Authentication successful
401	Invalid credentials (wrong email or password)
400	Bad request (missing email or password)

Security Notes

• Passwords are hashed using bcrypt before storage
• The JWT token includes user ID (sub), email, and roles in the payload
• Tokens should be transmitted only over HTTPS in production
• Store tokens securely and never expose them in URLs or logs